<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Create API key API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'security-api-create-api-key.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/security-api-create-api-key.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/security-api-create-api-key.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/security-api-create-api-key.html" rel="nofollow" target="_blank">../en/security-api-create-api-key.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="security-api.html">Security APIs</a></span>
»
<span class="breadcrumb-node">Create API key API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="security-api-clear-role-cache.html">« Clear roles cache API</a>
</span>
<span class="next">
<a href="security-api-put-privileges.html">Create or update application privileges API »</a>
</span>
</div>
<div class="section xpack">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="security-api-create-api-key"></a>Create API key API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a><a class="xpack_tag" href="https://www.elastic.co/subscriptions"></a>
</h2>
</div></div></div>

<p>Creates an API key for access without requiring basic authentication.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">POST /_security/api_key</code></p>
<p><code class="literal">PUT /_security/api_key</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-prereqs"></a>Prerequisites<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
To use this API, you must have at least the <code class="literal">manage_api_key</code> cluster privilege.
</li>
</ul>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The API keys are created by the Elasticsearch API key service, which is automatically enabled
when you configure TLS on the HTTP interface. See <a class="xref" href="configuring-tls.html#tls-http" title="Encrypting HTTP client communications">Encrypting HTTP client communications</a>. Alternatively,
you can explicitly enable the <code class="literal">xpack.security.authc.api_key.enabled</code> setting. When
you are running in production mode, a bootstrap check prevents you from enabling
the API key service unless you also enable TLS on the HTTP interface.</p>
<p>A successful create API key API call returns a JSON structure that contains the
API key, its unique id, and its name. If applicable, it also returns expiration
information for the API key in milliseconds.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>By default, API keys never expire. You can specify expiration information
when you create the API keys.</p>
</div>
</div>
<p>See <a class="xref" href="security-settings.html#api-key-service-settings" title="API key service settings">API key service settings</a> for configuration settings related to API key
service.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following parameters can be specified in the body of a POST or PUT request:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">name</code>
</span>
</dt>
<dd>
(Required, string) Specifies the name for this API key.
</dd>
<dt>
<span class="term">
<code class="literal">role_descriptors</code>
</span>
</dt>
<dd>
(Optional, array-of-role-descriptor) An array of role descriptors for this API
key. This parameter is optional. When it is not specified or is an empty array,
then the API key will have a <em>point in time snapshot of permissions of the
authenticated user</em>. If you supply role descriptors then the resultant permissions
would be an intersection of API keys permissions and authenticated user’s permissions
thereby limiting the access scope for API keys.
The structure of role descriptor is the same as the request for create role API.
For more details, see <a class="xref" href="security-api-put-role.html" title="Create or update roles API">create or update roles API</a>.
</dd>
<dt>
<span class="term">
<code class="literal">expiration</code>
</span>
</dt>
<dd>
(Optional, string) Expiration time for the API key. By default, API keys never
expire.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="security-api-create-api-key-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The following example creates an API key:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_security/api_key
{
  "name": "my-api-key",
  "expiration": "1d", <a id="CO648-1"></a><i class="conum" data-value="1"></i>
  "role_descriptors": { <a id="CO648-2"></a><i class="conum" data-value="2"></i>
    "role-a": {
      "cluster": ["all"],
      "index": [
        {
          "names": ["index-a*"],
          "privileges": ["read"]
        }
      ]
    },
    "role-b": {
      "cluster": ["all"],
      "index": [
        {
          "names": ["index-b*"],
          "privileges": ["all"]
        }
      ]
    }
  }
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/2065.console"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO648-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>optional expiration for the API key being generated. If expiration is not
provided then the API keys do not expire.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO648-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>optional role descriptors for this API key, if not provided then permissions
of authenticated user are applied.</p>
</td>
</tr>
</table>
</div>
<p>A successful call returns a JSON structure that provides
API key information.</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "id":"VuaCfGcBCdbkQm-e5aOx", <a id="CO649-1"></a><i class="conum" data-value="1"></i>
  "name":"my-api-key",
  "expiration":1544068612110, <a id="CO649-2"></a><i class="conum" data-value="2"></i>
  "api_key":"ui2lp2axTNmsyakw9tvNnw" <a id="CO649-3"></a><i class="conum" data-value="3"></i>
}</pre>
</div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO649-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>unique id for this API key</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO649-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>optional expiration in milliseconds for this API key</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO649-3"><i class="conum" data-value="3"></i></a></p>
</td>
<td align="left" valign="top">
<p>generated API key</p>
</td>
</tr>
</table>
</div>
<p>The API key returned by this API can then be used by sending a request with a
<code class="literal">Authorization</code> header with a value having the prefix <code class="literal">ApiKey</code> followed
by the <em>credentials</em>, where <em>credentials</em> is the base64 encoding of <code class="literal">id</code> and <code class="literal">api_key</code> joined by a colon.</p>
<div class="pre_wrapper lang-shell">
<pre class="programlisting prettyprint lang-shell">curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" http://localhost:9200/_cluster/health</pre>
</div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="security-api-clear-role-cache.html">« Clear roles cache API</a>
</span>
<span class="next">
<a href="security-api-put-privileges.html">Create or update application privileges API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>